EuroCD 3/EuroCD 3.iso/Programming/vbcc/machines/amigappc/doc/vclib.doc

Text File | 1998-06-24 | 5.1 KB | 236 lines

libvc.a - C library for the AmigaPPC version of vbcc


INTRODUCTION

    libvc.a is a (rather) ANSI compliant C library for use with the
    AmigaPPC (PowerUp) version of vbcc.

    It is written largely in C and some parts are not Amiga specific.

    Note that some functions dealing with floating point are placed in
    libm.a. Usually you will always want to link with libm.a, too. The
    default configuration will probably handle this. Otherwise you have
    have to specify the option -lm to vc.

    Some info about libamiga.a can be found in fd2libPPC.doc.


LEGAL

    libvc.a is public domain. Certain parts have been taken from other
    PD libraries (mainly libnix).
    libm.a is based on libmoto by Motorola, some freely distributable code
    from Sun and PD code. Please see libsrc/math for licenses.


STARTUP etc.

    The startup code will initialize SysBase, DOSBase, stdin, stdout and
    stderr. The arguments are passed from the 68k-side. So programs
    expecting arguments have to be started with ppcrun by Frank Wille.
    If no arguments have to be given, it can be started with PPCLoad or
    PPCDebug, too.


INLINING

    Several header-files provide support for inlining of certain library
    functions. If the preprocessor-symbol __INLINE_<function> is defined
    the corresponding function may be inlined. E.g if you compile with

        vc -O3 -D__INLINE_STRCPY

    then calls to strcpy() will be inlined. Note however that the symbol
    must be defined at the time string.h is included and, of course, that
    function inlining must be turned on.

    Not all library functions are prepared for inlining but only those
    that are reasonably small, are not implemented as macros and can
    safely be inlined. E.g. __INLINE_QSORT will be ignored.

    The symbol __INLINE_ALL will cause inlining of all functions which
    can be inlined.

    You must have the source to the library functions in the appropriate
    directories, e.g. strcpy must be reachable via

        #include "vbccppc:libsrc/string/strcpy.c"

    (This could be a problem when cross-compiling.)

    Also inline-assembly code is provided for several functions if the
    correct header was included. This also works without optimizations
    turned on.


STDIO

    The following functions are implemented at the moment:

    fopen()     binary and text modes are the same
    fclose()
    fflush()
    fgetc()
    ungetc()
    fputc()
    fgets()
    fputs()
    fread()
    fwrite()
    gets()      never use it...
    puts()
    ftell()
    fseek()
    remove()
    rename()
    rewind()
    setvbuf()
    setbuf()
    feof()
    ferror()
    prerror()
    tmpnam()
    tmpfile()   always returns an error at the moment
    fgetpos()
    fsetpos()
    printf()    taken from libnix
    fprintf()     "
    sprintf()     "
    vprintf()     "
    vfprintf()    "
    vsprintf()    "
    scanf()       "
    fscanf()      "
    sscanf()      "

    There are macros for a few functions. Some of them will cause a
    warning 129. This is necessary to make them fully conforming. You can
    safely ignore those warnings or use -dontwarn=129.


STDLIB

    The following functions do exist.

    malloc()
    free()
    calloc()
    realloc()
    rand()      taken from libnix
    srand()       "
    system()    not yet implemented
    abs()       inline assembly
    labs()      inline assembly
    div()
    ldiv()
    abort()
    atexit()
    getenv()    taken from libnix
    qsort()       "
    bsearch()     "
    strtol()      "
    strtoul()     "
    atol()        "
    atoi()        "
    atof()      taken from libnix; placed in libm.a
    strtod()      "


TIME

    The standard functions should exist. Taken from libnix.
    clock() always returns -1.

    CAUTION: time() is very slow! Calling it frequently can really
             kill performance!


STRING

    The standard functions should exist.
    Inline assembly is provided for several functions.


CTYPE

    The standard functions should exist.


LIMITS

    No functions.


FLOAT

    I do not know what has to be there, yet, but the most important things
    should be there (and approximately correct). No functions.


MATH

    The following functions are contained in libm.a. See libsrc/math/* for
    licenses.

    sin(), cos(), tan()
    sinh(), cosh(), tanh()
    asin(), acos(), atan(), atan2()
    exp(), log(), log10(), pow()
    ceil(), floor()
    sqrt()
    fabs()
    fmod()
    ldexp(). frexp()


STDDEF

    Currently defines size_t, fpos_t, ptrdiff_t, wchar_t, time_t, clock_t,
    NULL and offsetof. No functions.


STDARG

    Defines va_list, va_start, va_arg and va_end.


ASSERT

    Not really tested yet. No functions.


ERRNO

    The include file and errno is there, but most functions do not set
    errno. No functions.


SETJMP

    Taken from NetBSD.


SIGNAL

    signal() and raise() are there, but always return an error.


LOCALE

    localeconv() and setlocale() are there, but setlocale() does not do
    anything.


Again, there may be some errors or missing things in the include files
and the library.


COMPILING

    See the Makefile.


Volker                                              [e-mail]